<?php
/**
 *+------------------
 * Lflow
 *+------------------
 * Copyright (c) 2023~2030 gitee.com/liu_guan_qing All rights reserved.本版权不可删除，侵权必究
 *+------------------
 * Author: Mr.April(405784684@qq.com)
 *+------------------
 */
declare (strict_types=1);

namespace lflow;

use lflow\access\Page;
use lflow\access\QueryFilter;
use lflow\entity\CCOrder;
use lflow\entity\HistoryOrder;
use lflow\entity\HistoryTask;
use lflow\entity\Order;
use lflow\entity\Process;
use lflow\entity\Surrogate;
use lflow\entity\Task;
use lflow\entity\TaskActor;

/**
 * 数据库访问接口
 * 主要提供保存、更新、查询流程的相关table
 *
 * @author Mr.April
 * @since  1.0
 */
interface DBAccess
{
    /**
     * saveTask  保存任务对象
     * Date  2023/3/30 14:57
     *
     * @param \lflow\entity\Task $task
     */
    public function saveTask(Task $task): void;

    /**
     * saveOrder  保存流程实例对象
     * Date  2023/3/30 14:57
     *
     * @param \lflow\entity\Order $order
     */
    public function saveOrder(Order $order): void;

    /**
     * saveCCOrder  保存抄送实例
     * Date  2023/3/30 14:57
     *
     * @param \lflow\entity\CCOrder $ccorder
     */
    public function saveCCOrder(CCOrder $ccorder): void;

    /**
     * 保存流程定义对象
     *
     * @param process 流程定义对象
     */
    public function saveProcess(Process $process): void;

    /**
     * 保存任务参与者对象
     *
     * @param taskActor 任务参与者对象
     */
    public function saveTaskActor(TaskActor $taskActor): void;

    /**
     * 更新任务对象
     *
     * @param task 任务对象
     */
    public function updateTask(Task $task): void;

    /**
     * 更新流程实例对象
     *
     * @param order 流程实例对象
     */
    public function updateOrder(Order $order): void;

    /**
     * 更新抄送状态
     *
     * @param ccorder 抄送实体对象
     */
    public function updateCCOrder(CCOrder $ccorder): void;

    /**
     * 更新流程定义对象
     *
     * @param process 流程定义对象
     */
    public function updateProcess(Process $process): void;

    /**
     * 删除流程定义对象
     *
     * @param process 流程定义对象
     */
    public function deleteProcess(Process $process): void;

    /**
     * 更新流程定义类别
     *
     * @param type 类别
     *
     * @since 1.5
     */
    public function updateProcessType(string $id, string $type): void;

    /**
     * 删除任务、任务参与者对象
     *
     * @param task 任务对象
     */
    public function deleteTask(Task $task): void;

    /**
     * 删除流程实例对象
     *
     * @param order 流程实例对象
     */
    public function deleteOrder(Order $order): void;

    /**
     * 删除抄送记录
     *
     * @param ccorder 抄送实体对象
     */
    public function deleteCCOrder(CCOrder $ccorder): void;

    /**
     * 删除参与者
     *
     * @param taskId 任务id
     * @param actors 参与者集合
     */
    public function removeTaskActor(string $taskId, string $actors): void;

    /**
     * 迁移活动实例
     *
     * @param order 历史流程实例对象
     */
    public function saveHistory(HistoryOrder $order): void;

    /**
     * 更新历史流程实例状态
     *
     * @param order 历史流程实例对象
     */
    public function updateHistory(HistoryOrder $order): void;

    /**
     * 迁移活动任务
     *
     * @param task 历史任务对象
     */
//    public function saveHistory(HistoryTask $task): void;

    /**
     * 删除历史实例记录
     *
     * @param historyOrder 历史实例
     */
    public function deleteHistoryOrder(HistoryOrder $historyOrder): void;

    /**
     * 删除历史任务记录
     *
     * @param historyTask 历史任务
     */
    public function deleteHistoryTask(HistoryTask $historyTask): void;

    /**
     * 更新实例变量（包括历史实例表）
     *
     * @param order 实例对象
     */
    public function updateOrderVariable(Order $order): void;

    /**
     * 保存委托代理对象
     *
     * @param surrogate 委托代理对象
     */
    public function saveSurrogate(Surrogate $surrogate): void;

    /**
     * 更新委托代理对象
     *
     * @param surrogate 委托代理对象
     */
    public function updateSurrogate(Surrogate $surrogate): void;

    /**
     * 删除委托代理对象
     *
     * @param surrogate 委托代理对象
     */
    public function deleteSurrogate(Surrogate $surrogate): void;

    /**
     * 根据主键id查询委托代理对象
     *
     * @param id 主键id
     *
     * @return surrogate 委托代理对象
     */
    public function getSurrogate(string $id): ?Surrogate;

    /**
     * 根据授权人、流程名称查询委托代理对象
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<Surrogate> 委托代理对象集合
     */
    public function getSurrogateList(QueryFilter $filter, Page|null $page): array;

    /**
     * 根据任务id查询任务对象
     *
     * @param taskId 任务id
     *
     * @return Task 任务对象
     */
    public function getTask(string $taskId): ?Task;

    /**
     * 根据任务ID获取历史任务对象
     *
     * @param taskId 历史任务id
     *
     * @return 历史任务对象
     */
    public function getHistTask(string $taskId): ?HistoryTask;

    /**
     * 任务名称获取
     *
     * @param parentTaskId 父任务id
     *
     * @return array 活动任务集合
     */
    public function getNextActiveTasks(string $parentTaskId): array;

    /**
     * 根据流程实例id、任务名称获取
     *
     * @param orderId 流程实例id
     * @param taskName 任务名称
     * @param parentTaskId 父任务id
     *
     * @return array 活动任务集合
     */
    public function getNextActiveTasksX(string $orderId, string $taskName, string $parentTaskId): array;

    /**
     * 根据任务id查询所有活动任务参与者集合
     *
     * @param taskId 活动任务id
     *
     * @return List<TaskActor> 活动任务参与者集合
     */
    public function getTaskActorsByTaskId(string $taskId): array;

    /**
     * 根据任务id查询所有历史任务参与者集合
     *
     * @param taskId 历史任务id
     *
     * @return List<HistoryTaskActor> 历史任务参与者集合
     */
    public function getHistTaskActorsByTaskId(string $taskId): array;

    /**
     * 根据流程实例id查询实例对象
     *
     * @param orderId 活动流程实例id
     *
     * @return Order 活动流程实例对象
     */
    public function getOrder(string $orderId): ?Order;

    /**
     * 根据流程实例id、参与者id获取抄送记录
     *
     * @param orderId 活动流程实例id
     * @param actorIds 参与者id
     *
     * @return 传送记录列表
     */
    public function getCCOrder(string $orderId, string $actorIds): array;

    /**
     * 根据流程实例ID获取历史流程实例对象
     *
     * @param orderId 历史流程实例id
     *
     * @return HistoryOrder 历史流程实例对象
     */
    public function getHistOrder(string $orderId): ?HistoryOrder;

    /**
     * 根据流程定义id查询流程定义对象
     *
     * @param id 流程定义id
     *
     * @return Process 流程定义对象
     */
    public function getProcess(string $id): ?Process;

    /**
     * 根据流程名称查询最近的版本号
     *
     * @param name 流程名称
     *
     * @return Integer 流程定义版本号
     */
    public function getLatestProcessVersion(string $name): int;

    /**
     * 根据查询的参数，分页对象，返回分页后的查询结果
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<Process> 流程定义集合
     */
    public function getProcesss(QueryFilter $filter, Page $page): array;

    /**
     * 分页查询流程实例
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<Order> 活动流程实例集合
     */
    public function getActiveOrders(QueryFilter $filter, Page $page): array;

    /**
     * 分页查询活动任务列表
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<Task> 活动任务集合
     */
    public function getActiveTasks(QueryFilter $filter, Page $page): array;

    /**
     * 分页查询历史流程实例
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<HistoryOrder> 历史流程实例集合
     */
    public function getHistoryOrders(QueryFilter $filter, Page $page): array;

    /**
     * 根据参与者分页查询已完成的历史任务
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<HistoryTask> 历史任务集合
     */
    public function getHistoryTasks(QueryFilter $filter, Page $page);

    /**
     * 根据查询的参数，分页对象，返回分页后的活动工作项
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<WorkItem> 活动工作项
     */
    public function getWorkItems(QueryFilter $filter, Page $page);

    /**
     * 根据查询的参数，分页对象，返回分页后的抄送任务项
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<WorkItem> 活动工作项
     */
    public function getCCWorks(QueryFilter $filter, Page $page): array;

    /**
     * 根据流程定义ID、参与者分页查询已完成的历史任务项
     *
     * @param page 分页对象
     * @param filter 查询过滤器
     *
     * @return List<WorkItem> 历史工作项
     */
    public function getHistoryWorkItems(QueryFilter $filter, Page $page): array;

    /**
     * 根据类型clazz、Sql语句、参数查询单个对象
     *
     * @param clazz 类型
     * @param sql sql语句
     * @param args 参数列表
     *
     * @return 结果对象
     */
    public function queryObject($clazz, string $sql, object $args): object|null;

    /**
     * 根据类型clazz、Sql语句、参数查询列表对象
     *
     * @param clazz 类型
     * @param sql sql语句
     * @param args 参数列表
     *
     * @return 结果对象列表
     */
    public function queryList(string $clazz, string $sql, array $args = []): array;

    /**
     * 根据类型clazz、Sql语句、参数分页查询列表对象
     *
     * @param string                    $class
     * @param \lflow\access\QueryFilter $filter
     * @param string                    $sql
     * @param array                     $args
     * @param \lflow\access\Page|null   $page
     *
     * @return mixed
     */
    public function queryResult(string $class, QueryFilter $filter, string $sql, array $args, ?Page $page = null);

}